Projectを使ってIssueとIssue未満をいい塩梅で管理する方法について模索してみた

Issueまで至らない要望やメモ書き等をGitHub上でどうやって管理するか悩みものでした。Projectの動作を一つ一つ確認してみて、現状のワークフローに合わせて極力管理の負担が増えずに実現する方法を模索してみました。

#GitHub

haoyayoi

2021.07.21

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

以前チーム内でタスク管理の精度を上げるためにIssueとPRについてルール付を行い、ガイドラインとしてのテキストも作成しました。

これで迷いはなくなったと思っていましたが、一つ難点が。予めルール付したIssueの定義を埋めることができない、つまりはやるべきことが確定していない「ふわっとした」状態の所謂「提案」や「願望」を置くことができません。

コントリビューター向けテキストに書いた「マイルストーン」での解決も試みましたが、このマイルストーンはIssueとして確定したもののみを含めることができる仕様でした。要は私の動作把握漏れ。代わりの手段は無いものかとGitHubリポジトリの各機能を触っていたところ、Projectがそれに該当していました。

Projectの動作を理解している方は多いはずですが、Issue・マイルストーンとの組み合わせで使う場合の具体的なワークフローについては明記されている例を見かけず、割と曖昧です。実際のProject動作を見て、落とし所を検証してみました。

Projectの使い方

所謂オンラインでのカンバンです。Trello等を使ったことがある場合はお馴染みかもしれませんが、GitHubの場合は用途に応じてテンプレートが用意されています。

None
Basic Kanban
Automated Kanban
Automated Kanban with reviews
Bug triage

基本は状況に応じてカードをカラム間移動させることに変わり有りませんが、テンプレートによってはIssueやPRのステータスに応じて自動でカラム間の移動が行われます。

None

初期設定では一つもカラムがありません。カラム種類に応じた他のテンプレートにあるIssueやPRとのhook機能は存在しており、カラムやhookを手動追加することで他のテンプレートと同一の構成を作ることもできます。

Basic Kanban

以下3つのカラムで成り立つカンバンです。

ToDo
InProgress
Done

ポイントはIssueやPRとのhookが有効になっていないところです。作成したIssueやPRを管理することもできますが、進捗があってもカンバン上でのステータスには反映されません。故にIssueやPR等、GitHub特有の機能を伴わない、ベーシックな使い方で問題ない場合にはおすすめです。

Automated Kanban

見た目にはBasic Kanbanと変わりません。大きな違いとして、IssueやPRをProjectに紐付ると該当カンバン上に表示されるようになります。

実際に使ってみると期待する動作と以下2点で異なるかもしれません。

IssueはTodo扱いになり、完了するとDoneに移行する
PRはInProgress扱いになり、mergeされるとDoneに移行する

TodoからInProgressに、最後Doneへ、とはいかないのが特徴です。Issueを単純なTodoリストとして、ソースコードへのアクションをInProgressと見た場合にはマッチするかと思われます。

PRをmergeした際にIssueをクローズする仕組み(fix #XXX)にしておくと纏めてDone送りになり、手間が省けます。

Automated Kanban with reviews

Automated Kanbanと異なる点として以下の2点があります。

review中のPR用カラムReview in progressが追加され、approve数を得るとReviewer approvedに移行する
mergeに必要なapprove数を得たPR用カラムReviewer approvedが追加され、mergeされるとDoneに移行する

複数人のチームでreviewを機能させている場合に用いるテンプレートというわけです。

Bug Triage

バグフィックスを管理したいときに使えるテンプレートです。ポイントはGitHub上では「Bug」という区分がないところ。

Issueをhookさせておき、カンバン上に現れたIssueをバグフィックスの優先度にて応じて「High priority」か「Low priority」のいずれかに手作業で移行させる程度です。勿論優先度を更に細かくする手段もありです。

実際の運用

IssueとPRのhookを活用する

各テンプレートのhookを活用したい場合の一例として、以下のようなルールが考えられます。

IssueとPR作成時に忘れずにAutomated Kanban with reviewsのProjectに追加しておく
カンバン上でIssueとPRのカードを直接操作しない

IssueとPRの一覧ではステータスが俯瞰し難いため、状況をカンバンでフォローする、という構図です。Issueのカードには紐づくPRも表示されているため把握しやすくなります。

Reviewについては、

Review in progress にてレビューが完了していないPRをチェック
Reviewer approved でmergeしていないPRを完了する

という手続きにてReview漏れが減らせるかもしれません。

Issueとしては未だ起こせないTodoも管理する

Issueに必要な要件を満たせないものの追加したいパターン。例えば以下。

具体的な作業が固まっていないが要望として出ているもの
覚書に等しい状態
複数の内容が含まれていて整理が必要な案件

使い方の一例として、

カンバン上でCardとして追加(Issue未満)
決まった要件を追加していく
必要に応じて分割
Issue化出来るタイミングでIssueにする

というものが考えられます。

管理すべき範囲が広くみえそうですが、全員での共有時及び作業時に必ず見るべきはIssue Listのみです。上図内のカンバンについて、使い方の例を以下に挙げてみます。

Basic Kanbanの使い方

要望や覚書を詰める時に。個々で作成して下書きのような扱いにしても問題ありません。チーム全体で共有を義務化する必要もありません。使わない選択もありです。相談したいときにCardのLinkを渡して見てもらうとよいでしょう。Issueとまでは行かずになかったことにしたい場合はArchiveとしておきます。

カンバンに直接追加するとCardとして扱われます。Issue前段階であり、実作業は発生していないため進捗には値しません。要件を固めてIssueに変換するとIssue一覧にも追加され、カンバン上では表示がCardからIssueへ変わります。

このカンバンのポイントは、自身のIssueやCardが大量に溜まるところです。不要なCardは適度にArchiveし、大量のIssueに悩まされるようになった場合は今解決すべきIssueであるかを確認すべきです。必要に応じてマイルストーンにてこなす期日を調整しましょう。